home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 July / macformat-026.iso / mac / Shareware City / Sound / Macintosh Tracker Folder / Tracker AEIMP Protocol < prev    next >
Encoding:
Text File  |  1993-09-01  |  7.7 KB  |  185 lines  |  [TEXT/KAHL]
  1. Description of Tracker protocol:
  2.  
  3.  
  4. The Interface program controls the Servers through the use of
  5. Apple Events.  The following document describes how to use the
  6. controls so that either the Server of the Interface may be replaced.
  7.  
  8. In my terminology,
  9. Interface:  The program used to select the songs to play.
  10. Server:  The small program that actually plays the song.
  11.  
  12. Note that #define's for many of the values here can be found in
  13. the file "mac_events.h" which you can simply lift out and put into
  14. your own files.
  15.  
  16.  
  17.  
  18. Starting the Server:
  19.  
  20. The server is launched with an extended Open Document Apple Event.
  21. The event should contain one (1) file specification describing which
  22. song to open, in the normal Open Document way.  When launched, the
  23. server should continually call WaitNextEvent, waiting for the Open
  24. Event.  It should also be aware that a Quit Event might come at
  25. this point.
  26.  
  27. In addition to the required parameter, there are several
  28. additional parameters which describe the options to be used to
  29. play back the song:
  30.  
  31. Key Word         Code    Type
  32. -----------------------------------------------------------------------------------
  33. keyAntiAliasing  '∫Saa'  typeShortInteger
  34.   Boolean flag:  1 = use antialiasing algorithm, 0 = use fast algorithm
  35.  
  36. keyStereoOn      '∫Sso'  typeShortInteger
  37.   Boolean flag:  1 = use stereo playback, 0 = use mono playback
  38.  
  39. keySamplingRate  '∫Ssr'  typeShortInteger
  40.   Integer part of sampling rate in Hertz.  Should be converted to an unsigned
  41.   16-bit integer upon receipt, and then treated however your program needs to.
  42.   (Usually shifted left by 16 to create a Fixed type for the Sound Manager.)
  43.  
  44. keyNumRepeats    '∫Snr'  typeShortInteger
  45.   The number of times to repeat the song.  0 = repeat indefinitely, 1 = repeat once.
  46.   2 and up means repeat that many times.
  47.  
  48. keySpeed         '∫Ssp'  typeShortInteger
  49.   The speed in the number of ProTracker frames per second.  Usually, this is 50.
  50.  
  51. keyStereoMix     '∫Ssm'  typeShortInteger
  52.   How to mix for stereo.  0 is no mixing (hard separation), 100 is full mixing (mono).
  53.   Any number in between can be sent, but do not send negative numbers or numbers
  54.   that exceed 100.
  55.  
  56. keyLoudness      '∫Svl'  typeShortInteger
  57.   Value indicating loudness to play song at.  Generally, 0 is silence, and 64 is
  58.   the maximum value.  You may go as high as 255, so the tracker should constrain
  59.   the volume at 64 if it can't handle values greater than 64.  Negative values or
  60.   values greater than 255 should never be passed.
  61.  
  62. keyNumBits       '∫Bit'  typeShortInteger
  63.   Number of bits per signal level value to use.  This should either be 8 or 16.
  64.  
  65. keySenderPSN     '∫Psn'  typeProcessSerialNumber
  66.   Process serial number of the launching process.  This is used to send error
  67.   messages back to the launching process.
  68.  
  69. If these parameters are missing, the tracker should supply reasonable
  70. defaults.  This might happen if the user drags a song onto the tracker
  71. from the Finder.
  72.  
  73.  
  74.  
  75. Control Event:  Changing settings "on the fly."
  76.  
  77. The control event is a custom event.  The Event Class is '∫Tsp' and the
  78. Event Type is '∫Ctl'.  This event may contain any of the following parameters
  79. to be acted upon as soon as possible.
  80.  
  81. Key Word              Code    Type
  82. -----------------------------------------------------------------------------------
  83. keyAntiAliasing       '∫Saa'  typeShortInteger
  84. keyStereoOn           '∫Sso'  typeShortInteger
  85. keySamplingRate       '∫Ssr'  typeShortInteger
  86. keyNumRepeats         '∫Snr'  typeShortInteger
  87. keySpeed              '∫Ssp'  typeShortInteger
  88. keyStereoMix          '∫Ssm'  typeShortInteger
  89. keyLoudness           '∫Svl'  typeShortInteger
  90.  
  91. keyKeyPressCharacter  '∫Key'  typeShortInteger
  92.  
  93. All of the parameters which can also occur in the Open Document event have
  94. the same meaning here as they do in the Open Document event.
  95.  
  96. The KeyPress event originally faked keypresses to Espie's Tracker running it's
  97. unaltered UNIX interface behind the scenes.  That's how it got its name.
  98. However, it has changed to support general interactive control.
  99.  
  100. Usually, the parameter is interpreted as a character.  The following
  101. characters are currently supported:
  102.  
  103.   Character   Description
  104.   --------------------------------------------------------------
  105.   '>'         Fast Forward Begin
  106.     This indicates that the tracker should begin fast forwarding.  It is
  107.     sent when the user presses the mouse button DOWN in the fast forward
  108.     control.  The program should continue to fast forward the song until
  109.     notified otherwise.
  110.  
  111.   '<'         Rewind Begin
  112.     Rewind was originally intended to run the song backwards.  However, this
  113.     is nearly impossible, so currently it restarts the song.  In theory, the
  114.     program should continue to rewind until notified otherwise, so be
  115.     prepared to receive the normal play command (described next).
  116.  
  117.   '|'         Return to Normal Play (i.e. Cancel Fast Forward or Rewind)
  118.     This is sent when the user releases the mouse button from the rewind or
  119.     fast forward control.  If you are fast forwarding, resume normal tempo.
  120.     If you are not fast forwarding (then you probably got a rewind command)
  121.     just ignore it, but be prepared for it.
  122.  
  123.   '+'         Increase Loudness
  124.     Increase the volume a bit.  This isn't too important.
  125.  
  126.   '-'         Decrease Loudness
  127.     Likewise.
  128.  
  129.  
  130.  
  131. Returning Error Messages to the Launcher:
  132.  
  133. If the Server runs out of memory, encounters a really bad error, can't
  134. play the song, or something else happens, this event should be sent back
  135. to the Interface so that an alert can be presented to the user.
  136.  
  137. Note that these error messages describe FATAL errors.  Therefore, only one
  138. error should ever be sent per song and the tracker Server should exit
  139. immediately after sending the event.
  140.  
  141. The Event Class is '∫Tsp' and the Event ID is '∫Err'.  It contains one
  142. parameter of keyword '∫Er#' and type typeShortInteger.  Pass the following
  143. values for whichever error applies.
  144.  
  145. 0:  An unknown error occured.
  146. 1:  Server ran out of memory loading the song or setting up the buffers.
  147. 2:  An internal error occurred (generic "catch-all" type of error).
  148. 3:  Server can't open compressed files.  This is in here because Marc Espies's
  149.     Tracker will automatically pipe files through their appropriate decompressors
  150.     if there is an extention like ".zip" or ".Z".  Since the Macintosh doesn't
  151.     support pipes, the function "popen" sends this error.  Tell the user to
  152.     rename the file so that it doesn't have the extention any more.
  153.     As a side note:  I've modified the way I call Espie's main(argc,argv)
  154.     routine, so if "Tracker Server" ever sends this error, it is indicative
  155.     of a serious malfunction of the program.  I would suggest avoiding
  156.     using this error message for anything in your own Servers.
  157. 4:  The Server couldn't open the file.  This can be sent whenever the file can't
  158.     be open, for whatever reason that might be (file table full, too many
  159.     open working directories, etc...)
  160. 5:  Server Could't close file.  This will probably never happen, but it's in here
  161.     just in case.
  162. 6:  Server was told to open a file that isn't a song.  You should send this, but
  163.     you'll notice I haven't hacked Espie's calls to perror() and printf() to check
  164.     for his message "Not a song", so obviously it's not a high priority on
  165.     my list!
  166. 7:    68020 processor required.
  167.  
  168.  
  169.  
  170. What to do when the song is finished:
  171.  
  172. Just exit!  The Finder will automatically send the Interface an 'OBIT' event
  173. (Application Died) which the Interface should then interpret to mean it can
  174. start the next song or do whatever operation is called for.
  175.  
  176.  
  177.  
  178. Quit Events:
  179.  
  180. When the user cancels a song or shuts down the computer, a standard Quit Event
  181. is sent to the tracker program.  It should stop sound production, immediately
  182. dispose of any precomputed buffers, close sound channels, and exit.  This should
  183. all be done as soon as possible to prevent sluggishness.
  184.  
  185.